/* ========================================================================= */
/* ------------------------------------------------------------------------- */
/*!
  \file			pgprintparams.h
  \date			Jun 2012
  \author		TNick

  \brief		Contains the definition for PrintParams class


*//*


 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Please read COPYING and README files in root folder
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*/
/* ------------------------------------------------------------------------- */
/* ========================================================================= */
#ifndef __PGPRINTPARAMS_INC__
#define __PGPRINTPARAMS_INC__
//
//
//
//
/*  INCLUDES    ------------------------------------------------------------ */

#include	<cpg/cpg.h>
#include	<printing/printparams.h>

/*  INCLUDES    ============================================================ */
//
//
//
//
/*  CLASS    --------------------------------------------------------------- */


namespace   cpg     {

class	PgSpace;

/**
*	@brief	Printer related settings and ability to print
*
*	This class contains all the parameters that describe a print job. It is
*	used at space level to associate user settings with printers as
*	reported by the PrintManager singleton.
*
*	The class may be constructed either as a clone of a previously set-up
*	instance or a set of default parameters will be set-up. At any latter
*	time the doDefault() method will reset the values to ground state.
*
*	Here is a list of attributes that are stored with PrintParams:
*
*	<b>name()</b>@n
*	The PrintParams instances are grouped in a list at Gui::PgDocGui. The name
*	differentiates these instances for the user. Is changed using setName().
*
*	<b>printer()</b>@n
*	This is the device that we're using to generate output as an index inside
*	PrintManager's list. The device may be opperational (reported by the system),
*	may not exist in this system or may be some build-in virtual printer.
*	The printer is changed using setPrinter() and the integer is assumed to be
*	a valid index inside PrintManager's list.
*
*	<b>paper orientation</b>@n
*	Paper orientation may be either portrait or landscape. To querry use
*	isPortrait() or isLandscape(). To change it, use setLandscape() or
*	setPortrait().
*
*	<b>gray scalled output</b>@n
*	The printed output may be forced to a black and white output with
*	setGrayScaled(). the class reports its state with isGrayScaled(). For
*	devices that only support black and white there is no need to set this.
*
*	<b>duplex</b>@n
*	Printers that are able to use duplex printing may be set to a particular
*	configuration with setDuplexMode(). DuplexMode allows for simplex (no
*	duplex), duplex on either long or short side or use of default
*	configuration. duplexMode() tells current setting in an instance.
*
*	<b>page order</b>@n
*	The order of the pages in the output may be the natural one (first page is
*	printed first) or the reversed one (first page is printed last). Following
*	set of methods deal with that: isFirstPageFirst(), isLastPageFirst(),
*	setFirstPageFirst() and setLastPageFirst().
*
*	<b>origin of the coordinate system</b>@n
*	The printing margins may or may not be excluded when describing a print job.
*	Use setOriginPage() or setOriginPaper() to change the state. Use
*	isOriginPaper() or isOriginPage() to differentiate.
*
*	<b>type of print</b>@n
*	The application is able to print various content as described by the Mapping
*	enumeration:
*	- the content of the current view exactly as it is shown, scalled to exactly
*	match either the width or the height of the page;
*	- the content of the current space is scalled to fit the page
*	- the user provides a rectangle to print that is fitted to page
*	- one or more pages from current space.
*	Current state is reported by printType() and one may use setPrintType() to
*	change it. Note that associated values (like page ranges, the rectangle to
*	print) need to be set-up using additional calls.
*
*	<b>user-provided rectangle</b>@n
*	As previously mentioned one of the print modes is the one in which the
*	user provides a rectangle to be printed. setUserRect() method saves the
*	rectangle for this purpose and userRect() reports it back.
*
*	<b>range of pages</b>@n
*	Another mode is the one using pages. The user can provide a range of pages
*	in a list; the pages are represented using their 1-based index and a
*	(closed) interval is denoted by -1 value. So, the 1, 3, 4, -1, 6 sequence
*	will print pages 1, 3, 4, 5 and 6. If -1 is the last value all pages till
*	the end are printed; if it is th first, all pages including next index are
*	printed. If -1 is provided alone all the pages are to be printed.
*	See printRange() and setPrintRange().
*
*	<b>paper margins()</b>@n
*	Printable area is defined by the area of the paper from which we substract
*	some values for the margins. Each component represents the ammount to
*	substract on that particular side. Change this property with setMargins().
*
*	<b>size of the paper</b>@n
*	The (predefined) format of the paper is set using setPaperFormat() and
*	retrieved using paperFormat() .
*
*	<b>paper source</b>@n
*	Some printers have a number of phisical locations from where the paper
*	used to print on is taken. This allows setting that location through
*	setPaperSource() . paperSource() is used to querry the value.
*
*	<b>measurement units</b>@n
*	The values that are used to communicate with the user are expressed in some
*	units that can be set using setUnits() and retrieved with units() .
*
*/
class CPGSHARED_EXPORT PrintParams		: public BBlocks::PrintParams		{
	BBM_TRACK( PrintParams );

	//
	//
	//
	//
	/*  DEFINITIONS    ----------------------------------------------------- */

	/*  DEFINITIONS    ===================================================== */
	//
	//
	//
	//
	/*  DATA    ------------------------------------------------------------ */

protected:


	/**
	*	@brief	associated space
	*/
	PgSpace *				space_;


	/*  DATA    ============================================================ */
	//
	//
	//
	//
	/*  FUNCTIONS    ------------------------------------------------------- */

public:


	/**
	*	@brief	constructor; creates a default printer
	*/
	PrintParams			( PgSpace * spac );


	/**
	*	@brief	creates an instance from another
	*/
	PrintParams			( PrintParams * src );


	/**
	*	@brief	creates a default instance
	*/
	PrintParams			( void );


	/**
	*	@brief	destructor;
	*/
	~PrintParams  		( void );


	/**
	*	@brief	do the printing described by this structure
	*/
	bool				print					(
			QPrinter *			dest_p,
			QString &			s_err
			);


	/**
	*	@brief	associated container (where is this stored)
	*/
	inline PgSpace *	assocSpace				( void )
	{ return space_; }


	/**
	*	@brief	change the associated container (where is this stored)
	*/
	inline void			setAssocSpace			( PgSpace * new_val )
	{ space_ = new_val; }


	/*  FUNCTIONS    ======================================================= */
	//
	//
	//
	//

};	/*	class PrintParams	*/

/*  CLASS    =============================================================== */
//
//
//
//

}   //  namespace   cpg

#endif // __PRINTPARAMS_INC__
/* ------------------------------------------------------------------------- */
/* ========================================================================= */
